<!DOCTYPE HTML>
<html lang="en">
<head>
<title>Debugging Clients | AutoHotkey</title>
<meta name="description" content="This page lists some debugging clients or UIs known to be compatible with AutoHotkey." />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="static/theme.css" rel="stylesheet" type="text/css" />
<script src="static/content.js" type="text/javascript"></script>
</head>
<body>

<h1>Debugging Clients</h1>

<p>Additional debugging features are supported via <a href="https://xdebug.org/docs/dbgp">DBGp</a>, a common debugger protocol for languages and debugger UI communication. See <a href="Scripts.htm#idebug">Interactive Debugging</a> for more details. Some UIs or "clients" known to be compatible with AutoHotkey are listed on this page:</p>
<ul>
  <li><a href="#SciTE4AutoHotkey">SciTE4AutoHotkey</a></li>
  <li><a href="#XDebugClient">XDebugClient</a></li>
  <li><a href="#Notepad++">Notepad++ DBGp Plugin</a></li>
  <li><a href="#dbgp.ahk">Script-based Clients</a></li>
  <li><a href="#command-line-client">Command-line Client</a></li>
  <li><a href="#others">Others</a></li>
</ul>

<h2 id="SciTE4AutoHotkey">SciTE4AutoHotkey</h2>
<p><a href="http://fincs.ahk4.net/scite4ahk/">SciTE4AutoHotkey</a> is a free, <a href="https://www.scintilla.org/SciTE.html">SciTE</a>-based AutoHotkey script editor. In addition to DBGp support, it provides syntax highlighting, calltips/parameter info and auto-complete for AutoHotkey, and other useful editing features and scripting tools.</p>
<p>Debugging features include:</p>
<ul>
  <li>Breakpoints.</li>
  <li>Run, Step Over/Into/Out.</li>
  <li>View the call stack.</li>
  <li>List name and contents of variables in local/global scope.</li>
  <li>Hover over variable to show contents.</li>
  <li>Inspect or edit variable contents.</li>
  <li>View structure of objects.</li>
</ul>
<p><a href="http://fincs.ahk4.net/scite4ahk/">http://fincs.ahk4.net/scite4ahk/</a></p>

<h2 id="XDebugClient">XDebugClient</h2>
<p><a href="https://code.google.com/archive/p/xdebugclient/">XDebugClient</a> is a simple open-source front-end DBGp client based on the <b>.NET Framework 2.0</b>. XDebugClient was originally designed for PHP with Xdebug, but a custom build compatible with AutoHotkey is available below.</p>
<p><b>Changes:</b></p>
<ul>
  <li>Allow the debugger engine to report a language other than "php".</li>
  <li>Added AutoHotkey syntax highlighting.</li>
  <li>Automatically listen for a connection from the debugger engine, rather than waiting for the user to click <em>Start Listening</em>.</li>
  <li>Truncate property values at the first null-character, since AutoHotkey currently returns the entire variable contents and XDebugClient has no suitable interface for displaying binary content.</li>
</ul>
<p><b>Download:</b> <a href="https://www.autohotkey.com/download/tools/XDebugClient.zip">Binary</a>; <a href="https://www.autohotkey.com/download/tools/XDebugClient_src.zip">Source Code</a> (also see <a href="https://github.com/icsharpcode">SharpDevelop</a>, <a href="https://sourceforge.net/projects/dockpanelsuite/">Dockpanel Suite</a> and <a href="https://www.codeproject.com/Articles/14741/Advanced-TreeView-for-NET">Advanced TreeView</a>.)</p>
<p><b>Usage:</b></p>
<ul>
  <li>Launch XDebugClient.</li>
  <li>Launch AutoHotkey /Debug. XDebugClient should automatically open the script file.</li>
  <li>Click the left margin to set at least one breakpoint.</li>
  <li>Choose Run from the Debug menu, or press <kbd>F5</kbd>.</li>
  <li>When execution hits a breakpoint, use the Debug menu or shortcut keys to step through or resume the script.</li>
</ul>
<p><b>Features:</b></p>
<ul>
  <li>Syntax highlighted, read-only view of the source code.</li>
  <li>Breakpoints.</li>
  <li>Run, Step Over/Into/Out.</li>
  <li>View the call stack.</li>
  <li>Inspect variables - select a variable name, right-click, Inspect.</li>
</ul>
<p><b>Issues:</b></p>
<ul>
  <li>The user interface does not respond to user input while the script is running.</li>
  <li>No mechanisms are provided to list variables or set their values.</li>
</ul>

<h2 id="Notepad++">Notepad++ DBGp Plugin</h2>
<p>A DBGp client is available as a plugin for <a href="https://notepad-plus-plus.org/">Notepad++</a>. It is designed for PHP, but also works well with AutoHotkey.</p>
<p><b>Download:</b> See <a href="https://sourceforge.net/projects/npp-plugins/files/DBGP%20Plugin/">DBGp plugin for Notepad++</a>.</p>
<p><b>Usage:</b></p>
<ul>
  <li>Launch Notepad++.</li>
  <li>Configure the DBGp plugin via <i>Plugins</i>, <i>DBGp</i>, <i>Config...</i>
    <p class="note"><b>Note:</b> File Mapping must be configured.  Most users will not be debugging remotely, and therefore may simply put a checkmark next to <i>Bypass all mapping (local windows setup)</i>.</p>
  </li>
  <li>Show the debugger pane via the toolbar or <b>Plugins</b>, <b>DBGp</b>, <b>Debugger</b>.</li>
  <li>Open the script file to be debugged.</li>
  <li>Set at least one breakpoint.</li>
  <li>Launch AutoHotkey /Debug.</li>
  <li>Use the debugger toolbar or shortcut keys to control the debugger.</li>
</ul>
<p><b>Features:</b></p>
<ul>
  <li>Syntax highlighting, if configured by the user.</li>
  <li>Breakpoints.</li>
  <li>Run, Step Over/Into/Out, Run to cursor, Stop.</li>
  <li>View local/global variables.</li>
  <li>Watch user-specified variables.</li>
  <li>View the call stack.</li>
  <li>Hover over a variable to view its contents.</li>
  <li>User-configurable shortcut keys - Settings, Shortcut Mapper..., Plugin commands.</li>
</ul>
<p><b>Issues:</b></p>
<ul>
  <li>Hovering over a single-letter variable name does not work - for instance, hovering over <code>a</code> will attempt to retrieve <code>&nbsp;a</code> or <code>a </code>.</li>
  <li>Hovering over text will attempt to retrieve a variable even if the text contains invalid characters.</li>
  <li>Notepad++ becomes unstable if property_get fails, which is particularly problematic in light of the above. As a workaround, AutoHotkey sends an empty property instead of an error code when a non-existent or invalid variable is requested.</li>
</ul>

<h2 id="dbgp.ahk">Script-based Clients</h2>
<p>A script-based DBGp library and example clients are available from GitHub.</p><ul>
  <li>dbgp_console.ahk: Simple command-line client.</li>
  <li>dbgp_test.ahk: Demonstrates asynchronous debugging.</li>
  <li>dbgp_listvars.ahk: Example client which justs lists the variables of all running scripts.</li>
</ul>
<p>GitHub: <a href="https://github.com/Lexikos/dbgp">Lexikos / <strong>dbgp</strong></a></p>
<p>The DebugVars script provides a graphical user interface for inspecting and changing the contents of variables and objects in any running script (except compiled scripts). It also serves as a demonstration of the dbgp.ahk library.</p>
<p>GitHub: <a href="https://github.com/Lexikos/DebugVars.ahk#debugvars">Lexikos / <strong>DebugVars</strong></a></p>

<h2 id="command-line-client">Command-line Client</h2>
<p>A command-line client is available from <a href="https://xdebug.org/">xdebug.org</a>, however this is not suitable for most users as it requires a decent understanding of DBGp (the protocol).</p>

<h2 id="others">Others</h2>
<p>A number of other DBGp clients are available, but have not been tested with AutoHotkey. For a list, see <a href="https://xdebug.org/docs/remote">Xdebug: Documentation</a>.</p>

</body>
</html>
